…9569)

Follow-up of #9496

Under `install-strategy=linked`, a root `packageExtensions` rule that
adds a missing dependency installs and works at runtime, but every
command that reads the actual tree loses the edge:

- `npm ls --all --json` omits the extension-created dependency and its
provenance.
- `npm explain <dep>` fails with `No dependencies found matching <dep>`.
- `npm patch add <dep>` fails with `EPATCHNOTINSTALLED`.

Hoisted installs and normally-declared transitive deps are unaffected.

## References

Fixes #9568

…ch (#9570)

A workspace `packageExtensions` warning was printed twice per matching
workspace. A workspace appears in the inventory as two `isWorkspace`
nodes — the Link and its target — and `#warnWorkspacePackageExtensions`
warned for both. The fix skips the link (`node.isLink`) so each
workspace is warned once via its target node; the selector/`wouldMatch`
checks are otherwise unchanged.

## References

Follow up of #9496

Bot-generated transition of RFC **#55** to status `implemented`.

Moved to `implemented/0055-package-manifest-extensions.md`. Front-matter
`status` and the relevant date field were updated. `INDEX.md` was
regenerated.

Implementation: npm/cli#9496

Co-authored-by: npm CLI robot <npm-cli+bot@github.com>

## Summary

Adds an RFC for a root-owned `.npm-extension.mjs` / `.npm-extension.cjs`
file with a top-level `transformManifest(pkg, context)` extension point.

The proposal lets a project imperatively repair third-party package
manifests before Arborist reads dependency and peer edges. It builds on
the accepted [Package Manifest Extensions
proposal](#889) and its [npm CLI
implementation](npm/cli#9496), which established
the pre-resolution manifest repair phase, root-only authority model,
lockfile visibility model, and publish isolation for local dependency
metadata repairs.

`packageExtensions` remains the safer declarative default for common
metadata repairs. `.npm-extension` covers the cases where projects need
comments, upstream issue links, repeated transformations, conditional
logic, reading existing manifest values, deletion, dependency-range
replacement, or a local policy file that does not live in publishable
`package.json`.

## Motivation

`install-strategy=linked` makes dependency boundaries stricter by
avoiding accidental hoisting. That is useful for correctness, but it
exposes packages that import dependencies or type packages they did not
declare. The accepted `packageExtensions` RFC handles the most common
form of this problem: small deterministic additions to dependency and
peer metadata.

Some repairs are harder to keep clear as declarative JSON. During the
[Package Manifest Extensions proposal
discussion](#889 (comment)),
a Gutenberg migration example repeated the same optional `@types/react`
peer repair across many React-related dependencies. The declarative form
worked, but the underlying policy was really a named list or predicate:
"these packages import React types but do not declare an optional
`@types/react` peer."

Other local repairs need conditional logic, such as adding a type
package only when a matching runtime peer exists, copying an existing
peer range into a type dependency, narrowing a known bad peer range, or
throwing when upstream has fixed metadata and a local repair should be
removed. `packageExtensions` intentionally does not support that kind of
code.

This RFC proposes an explicit advanced escape hatch for those cases
while preserving npm's root-owned authority model, lockfile visibility,
and publish isolation.

## Why a separate extension file

The RFC intentionally keeps executable policy out of `package.json`. A
public package may need local dependency repairs for its own tests,
build, or linked-install migration, but it should not publish root-only
install policy to the registry manifest or packument.

`.npm-extension` is also deliberately not named `.npmfile` or shaped
like pnpm's `hooks.readPackage`. The proposal borrows the useful
manifest-transform idea from pnpm, but defines npm-specific semantics
for trust, lockfile hashing, `npm ci`, publish exclusion, disable
behavior, supported mutations, and future extension points.

## Notable semantics

- Only the root project owns `.npm-extension`.
- Workspace package manifests are not extension targets; non-root
workspace `.npm-extension` files warn and are ignored.
- Dependency package `.npm-extension` files are ignored.
- The only extension point in this RFC is top-level
`transformManifest(pkg, context)`.
- The extension point runs synchronously before dependency and peer
edges are read.
- Supported output changes are limited to `dependencies`,
`optionalDependencies`, `peerDependencies`, and `peerDependenciesMeta`.
- Unlike `packageExtensions`, the imperative form can delete supported
dependency entries and replace existing normal dependency ranges.
- Unsupported field changes such as `scripts`, `bin`, `exports`,
`types`, and `bundleDependencies` are rejected.
- `transformManifest` runs for non-root, non-workspace dependency
manifests from registry, git, remote tarball, local file, local
directory, and symlinked dependency sources.
- npm records an extension entry-file hash and minimal
`npmExtensionApplied` provenance in `package-lock.json`.
- `npm ci` verifies matching extension state without importing or
executing `.npm-extension`.
- Changed extension file bytes make `npm install` re-run
`transformManifest` across candidate manifests rather than relying on
selector-based selective re-resolution.
- Extension-created, extension-changed, and extension-removed dependency
metadata is visible through lockfile provenance and npm inspection
output.
- `.npm-extension.mjs` and `.npm-extension.cjs` are excluded from `npm
pack` and `npm publish`, even when listed in `files`.
- `ignore-extension=true` disables extension execution, and
`ignore-scripts=true` implies `ignore-extension=true` for commands that
would otherwise execute it.

## Relationship to `packageExtensions`

This RFC is not trying to replace `packageExtensions`. The declarative
feature should remain the first choice for small, reviewable manifest
repairs. The imperative extension file is for cases where the
declarative shape becomes repetitive, cannot express the needed local
policy, or cannot live in a publishable package manifest.

The RFC keeps the two features ordered and auditable:
`transformManifest` runs before `packageExtensions`, then npm reads
dependency and peer edges from the resulting effective manifest. That
lets imperative repairs inspect the upstream manifest before declarative
repairs are applied, while preserving the accepted `packageExtensions`
validation and provenance model.

## References

Follow up of #889 

---

> **Disclosure**: [Codex](https://chatgpt.com/codex/) and [Claude
Code](https://claude.com/claude-code) were used to draft the initial
version of this RFC and to iterate on it during review.